Prompts

Prompts define the instructions and behavioral guidance that shape how BindAI agents operate. At the simplest level, prompts can be provided through an agent’s instructions configuration. For larger applications, prompt content can be separated from application logic and reused across multiple agents.

What Is a Prompt?

A prompt provides the information and instructions an AI model needs to perform a task. Instructions can define:

The agent’s role
Expected behavior
Tone and style
Constraints
Output requirements
Domain-specific rules
How tools or retrieved information should be used

For example:

You are an experienced software architect.

Explain concepts clearly.

Keep responses concise.

Use practical examples whenever possible.

The prompt should focus on behavior and guidance rather than storing application data that changes between executions.

Using Instructions

The simplest way to configure an agent’s behavior is with instructions.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions(
        """
        You are a helpful assistant.

        Always answer clearly and politely.
        """
    )
    .build()
)

Instructions become part of the agent configuration and are used during execution. The builder approach is useful when the agent also requires tools, memory, knowledge, retrieval, middleware, or other capabilities.

Static Instructions

A static instruction remains the same for every execution.

agent = (
    Agent.builder()
    .name("writer")
    .model("openai:gpt-4.1-mini")
    .instructions(
        """
        You are a technical writer.

        Use clear language.

        Prefer concise explanations.
        """
    )
    .build()
)

Static instructions are useful when the agent’s role and behavior remain consistent. Examples include:

Customer support assistants
Technical writers
Research assistants
Coding assistants
Document reviewers

Dynamic Context

Many applications need to provide runtime information to an agent. For example:

document = "Large document content..."

result = agent.run(
    f"""
    Summarize the following document:

    {document}
    """
)

The agent instructions remain consistent while the document changes for each execution. For larger applications, dynamic context can also come from:

User input
Conversation state
Memory
Knowledge
Retrievers
Tools
Workflow state
Execution context

Runtime information should generally remain separate from static behavioral instructions.

Prompt Composition

Large instruction sets are easier to maintain when organized into logical sections. A structured prompt might contain:

Role

Goals

Rules

Constraints

Output Format

Examples

For example:

instructions = """
Role:
You are a senior Python engineer.

Goals:
Help developers solve practical programming problems.

Rules:
- Prefer simple solutions.
- Explain important tradeoffs.
- Use practical examples.

Output:
Provide concise explanations followed by code when appropriate.
"""

Structured instructions are easier to review and update than a single large paragraph.

Role Instructions

A prompt can establish the role an agent should perform. For example:

You are a senior software engineer specializing in Python.

Role instructions help establish the expected perspective and responsibilities of the agent. Keep role definitions specific enough to guide behavior without unnecessarily restricting useful responses.

Behavioral Instructions

Behavioral instructions define how the agent should respond. For example:

Explain technical concepts clearly.

Ask for clarification when required information is missing.

Prefer practical examples.

Do not invent facts.

Behavioral instructions should describe the behavior the application expects from the agent.

Output Instructions

Prompts can explicitly describe the expected output format. For example, Markdown:

Return your answer as Markdown.

Use headings and bullet points where appropriate.

JSON:

Return valid JSON only.

Tables:

Return the result as a Markdown table.

For strongly typed application responses, structured-output support can be preferable to relying only on textual formatting instructions. For example:

result = agent.run(
    "Generate a fictional person.",
    output=Person,
)

This lets application code work with a defined Python output type.

Structured Output and Prompts

Prompts and structured output solve different parts of the same problem. The prompt can explain what information should be generated:

Generate a fictional person with a name and age.

The output type can define the structure expected by application code:

from pydantic import BaseModel


class Person(BaseModel):
    name: str
    age: int

The type can then be supplied during execution:

result = agent.run(
    "Generate a fictional person.",
    output=Person,
)

This is generally more reliable for application-level data handling than asking the model to follow a textual format alone.

Reusing Instructions

Instructions can be reused through shared Python configuration. For example:

technical_writer_instructions = """
You are a technical writer.

Use clear and concise explanations.
"""

writer = (
    Agent.builder()
    .name("writer")
    .model("openai:gpt-4.1-mini")
    .instructions(technical_writer_instructions)
    .build()
)

reviewer = (
    Agent.builder()
    .name("reviewer")
    .model("openai:gpt-4.1-mini")
    .instructions(technical_writer_instructions)
    .build()
)

This keeps common behavioral guidance consistent across agents. Shared instructions should be used carefully. If two agents have substantially different responsibilities, give them focused instructions rather than forcing both into the same prompt.

Keeping Prompts Separate from Application Logic

For larger applications, avoid putting large instruction blocks throughout application code. Prompt definitions can be stored in dedicated files or modules. For example:

prompts/

├── support.md
├── sales.md
├── onboarding.md
├── summarization.md
└── review.md

This makes prompt content easier to:

Review
Version
Test
Reuse
Update independently from application logic

The application can load the prompt content and pass it to Agent.builder().instructions(...). The exact loading mechanism is an application design choice.

File-Based Prompt Example

A project can keep prompt content in a text or Markdown file. For example:

prompts/researcher.md

The application can load the file and use its contents as instructions:

from pathlib import Path
from bindai import Agent

instructions = Path("prompts/researcher.md").read_text()

agent = (
    Agent.builder()
    .name("researcher")
    .model("openai:gpt-4.1-mini")
    .instructions(instructions)
    .build()
)

This approach keeps long prompt definitions out of the main application module.

Prompt Variables

Applications sometimes need to incorporate runtime values into instructions. For example:

customer_name = "Alex"

instructions = f"""
You are a customer support assistant.

The customer's name is {customer_name}.
"""

For small amounts of dynamic information this can be sufficient. For larger or frequently changing information, prefer the appropriate BindAI capability:

User input for the current request
Conversation for conversational context
Memory for persisted information
Knowledge and retrieval for external information
Tools for external operations
Workflow state for multi-step execution

This prevents prompts from becoming an uncontrolled container for application state.

Prompts and Conversation

Prompt instructions and conversation input serve different purposes. Conceptually, an agent execution combines:

Agent Instructions
        +
Conversation Context
        +
Current User Input
        =
Model Execution

Instructions define how the agent should behave. Conversation context provides the surrounding interaction. The current user input provides the immediate request. Keeping these responsibilities separate makes conversational applications easier to reason about.

Prompts and Memory

Memory is an agent capability that can provide persisted information during execution. For example:

agent.use_memory(memory)

Prompts and memory therefore have different responsibilities:

Prompt — defines agent behavior and instructions.
Memory — provides stored information.
Conversation — provides conversational context.
User input — provides the current request.

Keep long-term application data in appropriate memory systems rather than continuously expanding the system instructions.

Prompts and Knowledge

Knowledge and retrieval provide external information that an agent can use during execution. For example:

agent.use_knowledge(knowledge)

A prompt can describe how the agent should use retrieved information. For example:

Use the provided documentation to answer questions.

If the required information is not available,
do not invent an answer.

The knowledge itself should remain in the knowledge system rather than being permanently embedded into the prompt. This is particularly important for large or frequently changing information sources.

Prompts and Tools

Tools allow agents to obtain information or perform actions through registered functions. For example:

agent.tool(search)

The prompt can explain when a tool should be preferred. For example:

When current information is required,
use the available search tool instead of relying
on information from the conversation.

This keeps behavioral guidance in the prompt while the actual capability remains implemented as a tool. The tool itself should contain the implementation logic rather than embedding operational logic into the prompt.

Prompts and Middleware

Middleware provides reusable behavior around agent execution. Prompts define model-facing behavioral guidance, while middleware handles application-level execution behavior. For example:

Prompt
  |
  | Defines agent behavior
  v
Agent
  |
  | Middleware surrounds execution
  v
Model Execution

Use prompts for model instructions and middleware for reusable cross-cutting application behavior such as logging, telemetry, metrics, or request processing.

Prompts in Workflows

When agents are used inside workflows, prompts can remain focused on the responsibility of the individual agent. For example:

Workflow
   |
   +── Research Agent
   |
   +── Analysis Agent
   |
   └── Review Agent

Each agent can have focused instructions rather than one large prompt attempting to control the entire workflow. This makes multi-step AI applications easier to maintain. For example, a research agent might be instructed to gather relevant information while an analysis agent focuses on interpreting that information. The workflow remains responsible for coordinating the stages.

Prompts and Specialist Agents

Multi-agent systems benefit from role-specific instructions. For example:

Research Agent
---------------
Find and organize relevant information.

Analysis Agent
--------------
Analyze the available information.

Writing Agent
-------------
Turn the analysis into a clear final response.

Each agent can therefore have a prompt designed specifically for its role. This is generally preferable to giving every agent a large prompt containing instructions for every possible responsibility.

Prompts and Agent Delegation

When an agent delegates work to another agent, the delegated agent should have clear instructions defining its responsibility. For example:

Primary Agent
     |
     +──> Research Agent
     |
     +──> Writing Agent
     |
     └──> Analysis Agent

The primary agent can coordinate the task while specialist agents focus on their assigned responsibilities. Clear role-specific prompts help reduce overlap between agents.

Prompt Organization

As a project grows, organize prompts by responsibility or domain. Example:

prompts/

├── support/
│   ├── assistant.md
│   └── escalation.md
│
├── sales/
│   ├── qualification.md
│   └── follow-up.md
│
├── documents/
│   ├── summarize.md
│   └── review.md
│
└── shared/
    ├── style.md
    └── safety.md

The exact directory structure is up to the application. The important principle is to keep reusable prompt definitions discoverable and separate from unrelated business logic.

Prompt Versioning

Prompts are application behavior and should therefore be version controlled alongside the application. When changing a prompt, consider whether the change affects:

Expected output
Tool usage
Safety behavior
Agent responsibilities
Workflow behavior
Structured output
Tests

Keeping prompts in source control makes changes reviewable and reproducible. For important applications, prompt changes should be treated similarly to code changes.

Testing Prompts

Prompts can be tested by executing the agent against representative inputs. Useful test cases include:

Normal requests
Missing information
Unexpected input
Tool-use scenarios
Knowledge-retrieval scenarios
Structured-output scenarios
Error conditions
Multi-agent handoffs

Prompt testing is particularly useful when an application depends on consistent agent behavior.

Prompt Size

Avoid placing large amounts of information directly into agent instructions. Large static instructions can make prompts harder to maintain and can consume model context unnecessarily. Prefer:

Prompts for behavior
Conversation for conversational context
Memory for persisted information
Knowledge and retrieval for external information
Tools for actions
Workflow state for orchestration data

This separation keeps each part of the BindAI architecture responsible for the information it is designed to manage.

Provider Independence

BindAI provides a common agent interface across supported model providers. The same general prompt strategy can therefore be used while changing the configured model:

Agent.builder().model("openai:gpt-4.1-mini")

or:

Agent.builder().model("anthropic:claude-sonnet-4")

or:

Agent.builder().model("ollama:llama3")

Prompt behavior can vary between models, however, so applications should test important prompts against the provider and model combinations they intend to support.

Complete Example

A complete agent can combine reusable instructions with tools, memory, knowledge, and retrieval:

from pathlib import Path

from bindai import Agent


instructions = Path("prompts/research-assistant.md").read_text()

agent = (
    Agent.builder()
    .name("research-assistant")
    .model("openai:gpt-4.1-mini")
    .instructions(instructions)
    .tool(search)
    .memory(memory)
    .knowledge(knowledge)
    .retriever(retriever)
    .build()
)

result = agent.run("Research BindAI and summarize its architecture.")

print(result.output)

The prompt defines the agent’s behavior while the other BindAI capabilities provide the information and actions required to perform the task.

Best Practices

Keep instructions focused on the agent’s responsibility.
Separate behavioral instructions from runtime data.
Reuse common instructions where appropriate.
Keep prompts in dedicated files or modules as applications grow.
Version-control important prompts with the application.
Clearly define expected output formats.
Prefer structured output when application code requires a defined Python result.
Keep large documents out of static instructions.
Use tools for actions and external operations.
Use memory for persisted information.
Use knowledge and retrieval for external information.
Use workflows for multi-step orchestration.
Give specialist agents focused role-specific instructions.
Test important prompts against the model providers the application supports.
Treat significant prompt changes as application behavior changes.

A well-organized prompt strategy keeps agent behavior predictable while allowing the rest of the BindAI architecture—tools, memory, knowledge, retrieval, workflows, and multi-agent execution—to handle their respective responsibilities.

​Prompts

​What Is a Prompt?

​Using Instructions

​Static Instructions

​Dynamic Context

​Prompt Composition

​Role Instructions

​Behavioral Instructions

​Output Instructions

​Structured Output and Prompts

​Reusing Instructions

​Keeping Prompts Separate from Application Logic

​File-Based Prompt Example

​Prompt Variables

​Prompts and Conversation

​Prompts and Memory

​Prompts and Knowledge

​Prompts and Tools

​Prompts and Middleware

​Prompts in Workflows

​Prompts and Specialist Agents

​Prompts and Agent Delegation

​Prompt Organization

​Prompt Versioning

​Testing Prompts

​Prompt Size

​Provider Independence

​Complete Example

​Best Practices